home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 38 / Amiga Format CD38 (1999-03-15)(Future Publishing)(GB)(Track 1 of 3)[!][issue 1999-04].iso / -seriously_amiga- / programming / other / ira_src / ira.doc < prev    next >
Text File  |  1999-02-03  |  19KB  |  442 lines
  1.  
  2.  
  3.                       ________________
  4.                      /___/_________/_/\----- - -  -   -   -
  5.                     /   /         /  \ \
  6.                    /   /  ____   /    \ \
  7.                   /   /  / / /  /  /\  \ \----- - -  -   -   -
  8.                  /   /  / / /  /  / /\  \ \
  9.                  \   \  \ \/  /  / /  \  \ \
  10.                   \   \  \/  /  /  ¯¯¯¯\  \ \----- - -  -  -   -
  11.                    \   \     \  ¯¯¯¯¯¯¯¯   \ \
  12.                     \   \     \    ______   \ \ :
  13.                     /   /  /\  \   \ \  :\   \ \|/--- - -  -  -   -
  14.                    /   /  / /\  \   \ \ ° \   \ *--
  15.                   /   /  / /  \  \   \/    \   \|\
  16.                   ¯¯¯¯¯¯¯¯¯    ¯¯¯¯¯¯¯      ¯¯¯¯:
  17.  
  18.                                                 
  19.  
  20.                       IRA  V1.05beta  05/95
  21.  
  22.                       Shareware reassembler
  23.  
  24.           (C) 1993 Tim Ruehsen  SiliconSurfer/Phantasm
  25.  
  26.                     SHAREWARE 20US$/25DM CASH
  27.  
  28.  
  29.  
  30. FORWORD
  31. ¯¯¯¯¯¯¯
  32. First, this is not the final version of IRA. Everybody's comments or ideas
  33. are welcome, even if no shareware fee was paid. Don't be afraid.
  34. The future will bring you 6888x (FPU) and MMU commands, perhaps the IRA
  35. will get interactive. That depends on your comments and letters.
  36. What about a special reassembling part for printer drivers or stuff like that ?
  37. Perhabs, this is more important than FPU commands.
  38. If you find any errors, send me a disk with the program that causes trouble
  39. and tell me what command line you used. The disk will be returned with the
  40. newest version of IRA and some PD stuff.
  41.  
  42.  
  43. DESCRIPTION
  44. ¯¯¯¯¯¯¯¯¯¯¯
  45. This is version V1.05 of my reassembler IRA. Reassembler means that IRA
  46. translates any executable or binary file into an assembler sourcecode that
  47. might immediately be translated back by an assembler. E.g., you can do that
  48. with a debugging option. After that you can examine that program with any
  49. debugger. That's fine for finding and analysing viruses, repairing old programs,
  50. even optimising alien programs.
  51.  
  52. When translating back with an assembler, switch optimising off,except you know
  53. exactly what you're doing !!!
  54.  
  55. IRA is for use from CLI/SHELL.
  56.  
  57. IRA has some command line options. Just type 'ira' to get a short description.
  58.  
  59. This version works fine with the MC68000 and the MC68010 processor.
  60. FPU and MMU commands are not implemented yet.
  61. Reassembling programs for 68020+ processors may cause trouble with some
  62. addressing modes.
  63. For example: (0,A0) and (0,A0) seems to be the same, but the first may be
  64. (d16,An) and the second (bd,An,Xn) with Xn suppressed (and bd might be 16
  65. or 32 bit). There are other ambiguous addressing modes.
  66. IRA has no problems with that, but assemblers can't know what the original
  67. addressing mode was, so problems with running a reassembled file may occur.
  68.  
  69. DESCRIPTION OF THE COMMAND-LINE OPTIONS
  70. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  71. The default values are in brackets.
  72.  
  73. -M680x0 (-M68000)
  74.         This specifies the type of processor for which the program should
  75.         be reassembled. This doesn't has anything to do with the machine
  76.         you're running IRA on. Most programs are written for 68000 CPUs.
  77.         If anything other than -M68000 is specified a MACHINE statement
  78.         in the .ASM file is created. This works fine with the PhxAss
  79.         assembler (see below). For any other assembler this statement
  80.         possibly has to be changed.
  81.  
  82. -BINARY (off)
  83.         IRA automatically recognises if the sourcefile is an executable,
  84.         an object file or any other (binary). It may happen that some
  85.         kind of binary data is recognised as an executable. To avoid this
  86.         make use of the -BINARY option.
  87.  
  88. -a      (off)
  89.         This option makes IRA append the address and data of an instruction
  90.         to every line. That is pretty useful to me. E.g. when code and data
  91.         is mixed, you can manually delete some instructions to replace them
  92.         by DC.x directives.
  93.  
  94. -INFO   (off)
  95.         Use this option to get some information about the hunk structure of
  96.         your sourcefile.
  97.  
  98. -OFFSET=<OFFSET> (-OFFSET=0)
  99.         When the sourcefile is relocated by IRA the offset value is added to
  100.         the relocation. Why should I do that ?
  101.         If you want to run an executable at a specific location in memory
  102.         you specify the address of that location with the -OFFSET option
  103.         in combination with the -KEEPBIN option. After running IRA you can
  104.         load the .BIN file to the specific location and execute it. You just
  105.         have to know what you're doing (e.g. contents of registers and so on).
  106.         The second, more useful application is to write a part of memory to a
  107.         file, then create a .ASM file with the -OFFSET option. You have to take
  108.         the address of the memory location as offset. E.g. you can create your
  109.         own kickfile with your own modifications (is it legal ?), of course
  110.         some additional work on the .ASM file has to be done.
  111.         OFFSET can be decimal or hexadecimal (e.g. -OFFSET=$4FF0).
  112.  
  113. -TEXT=x (off)
  114.         Since version 1.03 there is only one method for finding text left. The
  115.         whole code and data sections are searched for text which is printed
  116.         out to <stdout>. It may happen that some stupid text lines show up, so
  117.         you have to decide yourself about every line to include into the .ASM
  118.         file.
  119.  
  120. -KEEPZH (off)
  121.         There are files that have hunks with a length of zero. By default
  122.         these hunks don't appear in the .ASM file. If you want them to see
  123.         just use this option. There are executables where you have to use
  124.         this option because they work with there own SEGMENT structure.
  125.  
  126. -KEEPBIN (off)
  127.         Before the first pass an executable is relocated by IRA and written
  128.         to a .BIN file. Normally, this file is deleted at some point but if
  129.         you want to keep it for some purpose use the -KEEPBIN option.
  130.         E.g. for a <type >x.hex x.bin opt h>.
  131.  
  132. -OLDSTYLE (depends on the -M680x0 option)
  133.         This option forces IRA to use the old Motorola syntax like D16(PC)
  134.         instead of (D16,PC). By default this option is used for 68000 and
  135.         68010 processors.
  136.  
  137. -NEWSTYLE (depends on the -M680x0 option)
  138.         This option forces IRA to use the new Motorola syntax like (D16,PC)
  139.         instead of D16(PC). By default this option is used for 68020, 68030
  140.         and 68040 processors.
  141.  
  142. -SPLITFILE (off)
  143.         With this option the .ASM file is split up. Every section is put into
  144.         an own file. One 'main' file is created to include these files via
  145.         INCLUDE statements. What is it for ? I don't know. I was asked for
  146.         this option.
  147.  
  148. -PREPROC (off)
  149.         This option will turn on pass 0. That is to find data in code sections
  150.         and even code in data sections (e.g some old compilers put their
  151.         jumptables into data sections). Found data is checked for text.
  152.         This option normally works very fine for compiled programs. But there
  153.         may be problems like these:
  154.  
  155.         - parts of code may be seen as data. This comes for
  156.           o code that is jumped to by (An), D16(An) or D8(PC,An)
  157.             (jumptables, pointers to code, ...).
  158.           o interrupt code that is only referenced by pointer (installation).
  159.           o code that is never used.
  160.  
  161.         - parts of data may be seen as code. This comes for
  162.           o crypted or crunched code.
  163.  
  164. -ENTRY=<OFFSET> (-ENTRY=0)
  165.         If you know, that a file has data at the beginning (eg. bootblocks),
  166.         you specify the (relative) adress where IRA should begin with
  167.         code-scanning. For bootblocks: -ENTRY=$C .
  168.  
  169. -BASEREG[=n[,adr,sec]]
  170.         n is the number of the base register, adr the address with that the
  171.         base register is loaded and sec the section that n is related to.
  172.  
  173.         You can use this option if the program uses the smalldata model. It
  174.         will provide you with a more readable .ASM file.
  175.         Smalldata model means the access to data is made by D16(An), and the
  176.         register An has to be preloaded by the SMALLDATABASE value. A lot of
  177.         compilers use A4 as baseregister and the address of the datasection
  178.         plus 32766 as the SMALLDATABASE.
  179.         A good way to find out if a program makes use of the smalldata model
  180.         is the following:
  181.         1. Type <IRA >x -a -info -basereg test>
  182.         2. Look at the file test.asm and x with an editor.
  183.            If there are memory accesses by D16(An) (e.g. move.l -32754(A4),D0)
  184.            look at the file x. There may be lines like BASEREG 00000008: A4.
  185.            The first number is the hexadecimal address of an instruction that
  186.            has A4 as destination register. Look at this address in the file
  187.            test.asm. You may find a line like LEA SECSTRT_1,A4. Perhabs, A4
  188.            is the baseregister and SECSTRT_1 the SMALLDATABASE. Now memo the
  189.            address of SECSTRT_1 (=adr).
  190.         3. Type <IRA -a -info -basereg=4,adr,1 test>
  191.         4. Look at test.asm and you will see LAB_xxxx instead of D16(A4).
  192.         5. The line NEAR A4,1 in test.asm tells the assembler to use the
  193.            smalldata model. This directive may differ from assembler to 
  194.            assembler.
  195.  
  196.         As always, be careful when modifying a program. Often code and data
  197.         is mixed or there are some program protection technics that makes it
  198.         hard to modify and run a program.
  199.  
  200.  
  201. -CONFIG (off)
  202.         First, you can control the IRA settings with this option. That means 
  203.         you can specify the parameters that are otherways controlled via the
  204.         command-line options. Second, you can specify addresses where to find
  205.         code. This is useful for addresses where the -PREPROC option oversees
  206.         code (for whatever reason). Third, you can specify symbols that are
  207.         inserted instead using the 'LAB_xxxx' type.
  208.  
  209.         In combination with the -PREPROC option a new .cnf file is created.
  210.         All the code areas found by PASS0 are then written to this .cnf file.
  211.         In addition, most of the command-line options are included, too.
  212.         So, for the next calling of IRA you won't need to specify all of the
  213.         command-line options you used to.
  214.  
  215.         If a .cnf file exists, a possible new one does not overwrite the old
  216.         one. The name of the new one just get a '1' joined to it's name.
  217.         Look out for that.
  218.  
  219.         Here are the directives that IRA understands:
  220.  
  221.         o MACHINE 680x0   (same as -MACHINE option)
  222.  
  223.         o OFFSET offset   (same as -OFFSET option [hex or decimal])
  224.  
  225.         o BASEREG An      (n specifies the base register for the smalldata)
  226.                           (model. You can leave the 'A' out.              )
  227.         o BASEADR adr     (adr specifies the base address that the base   )
  228.                           (register is loaded with. [hex or decimal]      )
  229.         o BASESEC sec     (sec specifies the number of the section that   )
  230.                           (the base address is related to.                )
  231.  
  232.         o SYMBOL name adr (name is a string (the name for the symbol).    )
  233.                           (adr is the address of the symbol.              )
  234.  
  235.         o CODE adr1 adr2  (adr1 is the starting address of a code area.   )
  236.                           (adr2 is the end address of this area. You can  )
  237.                           (leave adr2 out and use the -PREPROC option. In )
  238.                           (this case PASS0 automatically finds the end of )
  239.                           (the code area.                                 )
  240.  
  241.         Try the -CONFIG option out in combination with the -PREPROC option.
  242.         IRA will create a .cnf file that you can look at for better
  243.         understanding.
  244.  
  245.  
  246. HOW TO REASSEMBLE A PROGRAM
  247. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  248. First, you have to be sure that your Assembler, Linker and IRA work fine.
  249. That goes like follows:
  250.   (Let's assume the linker is called LN, the ASSEMBLER is called AS and the
  251.    program is called TEST.)
  252.  
  253.   1. Type <IRA -a TEST TEST1.S>
  254.   2. Type <AS -n TEST1.S>           (assume -n to be the NO_OPTIMISE flag)
  255.   3. Type <LN TEST1.O>
  256.   4. Type <IRA -a TEST1 TEST2.S>
  257.   5. Type <FDIFF TEST1.S TEST2.S RESYNC 1>
  258.  
  259. If no error pops up until now it's very likely that TEST1 will work. (Try it).
  260. If FDIFF tells you that there are differences between TEST1.S and TEST2.S you
  261. have to be careful with running TEST1 because there is at least one bug in
  262. IRA (I don't think so!) or in your assembler. Try to reproduce the error in
  263. a small file and tell me about it. I could provide an assembler buglist here.
  264.  
  265. If you got no problems with the five points above you can start with editing
  266. TEST1.S. First, try to find all data that is hidden in code sections and
  267. replace the instructions with DC.W directives. If you have done so try
  268. assembling TEST1.S with an optimising assembler (should work).
  269. To find parts of text use the -TEXT option. Or use the -KEEPBIN option and
  270. type <type >test.hex TEST.BIN opt h> and look at TEST.HEX for text.
  271.  
  272. To collect some experience it'll be better to begin with short programs.
  273.  
  274.  
  275. To reassemble bootblocks, disktracks or memory take a monitor program and put
  276. these things into a file. Then invoke IRA.
  277.  
  278.  
  279. WHAT ASSEMBLER CAN I USE ?
  280. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  281. You can use any assembler you want, but minor problems may occur:
  282.  
  283.   - There may be problems with the SECTION, MACHINE and NEAR directives.
  284.     Change these lines by hand or tell me the name and version of your
  285.     assembler and the syntax of the above directives. So I could build a
  286.     command-line option to switch between different assemblers.
  287.   - Some assemblers can't handle more than 2^16-1 (65535) lines. Get the
  288.     GigaPhxAss from Frank Wille (see below) for the big programs.
  289.   - If code and data is mixed in a code hunk you have to switch optimising
  290.     off when you run the assembler. Else the chance of having a damaged
  291.     program is very high. Some assemblers have problems with that.
  292.  
  293. Tell me about any problems !!!
  294.  
  295. I use PHXASS from Frank Wille, a fast and excellent 680x0, FPU and MMU
  296. assembler. You can get it on AMINET somewhere.
  297. Or send a disk (with PD stuff, of course) and a self addressed envelope
  298. to:
  299.        Frank Wille
  300.        Auf dem Dreische 45
  301.        32049 Herford
  302.        GERMANY
  303.  
  304. Thanks a lot, Frank !
  305.  
  306.  
  307. CONDITIONS
  308. ¯¯¯¯¯¯¯¯¯¯
  309. IRA is shareware. The program may be freely distributed
  310. and copied, as long as the following conditions are
  311. fulfilled:
  312.  
  313. - The sales price must not be higher than the cost of
  314.   an (empty) disk plus a nominal copying fee plus
  315.   costs for shipping. The total price must not be higher
  316.   than 6 US$ or 10 DM.
  317. - All parts of the program and the documentation must
  318.   be complete. The distribution of single parts is not
  319.   allowed.
  320. - IRA or parts of it must not be sold in combination with
  321.   or as part of commercial software.
  322. - Program and documentation must not be changed in any way.
  323.   Exception is the use of archivers such as LHArc and packers
  324.   like "Imploder" or "Powerpacker", as long as it is possible
  325.   to retrieve the original program/data.
  326.  
  327.  
  328. I explicitly do not guarantee for the correct functioning of IRA.
  329. I explicitly reject any responsibility for any consequences from the use
  330. of IRA whatsoever. This includes, but is not limited to, secondary 
  331. consequences, personal injuries or other kinds of side effects.
  332.  
  333.  
  334.  
  335. I want to ask everybody, who uses IRA frequently to send the amount of
  336.  
  337.      20 US$  or  25 DM
  338.  
  339. to the following address:
  340.  
  341.    Tim Ruehsen
  342.    Johannes-Rabe-Stieg 8
  343.    21033 Hamburg
  344.    Germany
  345.  
  346. Please send only cash.
  347.  
  348.  
  349.  
  350. ERROR REPORTS
  351. ¯¯¯¯¯¯¯¯¯¯¯¯¯
  352. If you find any errors, send me a disk with the program that causes trouble
  353. and tell me what command line you used. The disk will be returned with the
  354. newest version of IRA and some PD stuff.
  355. If you have questions or ideas about IRA send me a letter,
  356.  
  357. DON'T send any assemblers WITHOUT (short) documentation or I can't help you.
  358.  
  359. phone me  GERMANY : 040-7216995  or
  360. EMAIL me  SiliconSurfer@Blackbox.shnet.org
  361.           SiliconSurfer@Dame.shnet.org
  362.  
  363. You can download the newest version of IRA from me with up to 19200 baud.
  364.  
  365.  
  366.  
  367. HISTORY
  368. ¯¯¯¯¯¯¯
  369. V1.01    First released version.
  370.  
  371. V1.02
  372.        o CHIP and FAST hunks are now recognised.
  373.        o Addressing mode D8(PC,An) is now used with a label.
  374.        o Removed a never-ending-loop problem that came up with a special
  375.          program protection (a hack in the hunk structure).
  376.        o Removed the multiple-label problem.
  377.        o The MACHINE directive is no longer used in 68000 programs.
  378.        o Some of the command-line options changed.
  379.  
  380. V1.03beta
  381.        o Text in DATA hunks is now recognised.
  382.        o Much better -TEXT=1 option.
  383.        o Removed the -TEXT=2 option.
  384.        o A stand-alone postprocessor for symbolizing library calls is added.
  385.          See irapost.doc.
  386.        o A new pass (PASS 0) is added for finding data in CODE hunks. It is
  387.          switched on by the new -PREPROC option. See above for more.
  388.        o Symbol hunks are now processed and symbols inserted into the source.
  389.        o Resident structures are searched for and extra symbols set. That means
  390.          .library and .device files are much better deassembled.
  391.        o The new command-line option -CONFIG is added. Coming up with this is
  392.          a an edible .cnf file. See above.
  393.        o Much less memory intensive, especially when having large data parts.
  394.        o The -CACHE option no longer exists due to using buffered i/o now.
  395.        o Some (major) bugs with 020+ code fixed.
  396.        o Sometimes no labels were printed - fixed.
  397.        o Shortened the help-text. Now it fits on a 25 lines console window.
  398.  
  399. V1.04
  400.        o intern version for friends, eg special TJSeka version...
  401.  
  402. V1.05beta
  403.        o some bugs removed
  404.        o new command-line option added: -ENTRY (not much tested)
  405.        o HUNK_DREL32 (V37+) and HUNK_RELOC32SHORT (V39+) added.
  406.  
  407.  
  408. KNOWN BUGS
  409. ¯¯¯¯¯¯¯¯¯¯
  410.        - some lines of text (eg. scrollies) are too long for PhxAss.
  411.        - there are probs with some 68020 adressing modes
  412.        - btst.b #x,<ea> with x>7 (fault of any assemblers) is translated
  413.          to btst #(x MOD 8),<ea> instead of being translated to dc.w xxxx
  414.        - a Kickstart file causes probs ... dont't know why.
  415.  
  416. TO DO
  417. ¯¯¯¯¯
  418.        - a prefs editor
  419.        - FPU/MMU & 68060 codes
  420.        - interactivity of IRA
  421.  
  422.  
  423. BETA-TESTERS
  424. ¯¯¯¯¯¯¯¯¯¯¯¯
  425. Thanks to all the testers of IRA (poor number):
  426.  
  427. Cristian Wasner
  428. Frank Wille
  429. Marcus C. Degler
  430. Morten Erikson
  431. Tino.
  432.  
  433. Special thanx to Morten who coded the original version of the IRA postprocessor.
  434.  
  435.  
  436.  
  437.  
  438. Good Night, 'till next version.
  439.  
  440.  
  441.                      TIM RUEHSEN
  442.